<!DOCTYPE HTML>
<html lang="en">
<head>
<title>StatusBarWait - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The StatusBarWait command waits until a window's status bar contains the specified string." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>StatusBarWait</h1>

<p>Waits until a window's status bar contains the specified string.</p>

<pre class="Syntax"><span class="func">StatusBarWait</span> <span class="optional">, BarText, Timeout, Part#, WinTitle, WinText, Interval, ExcludeTitle, ExcludeText</span></pre>
<h2>Parameters</h2>
<dl>

  <dt>BarText</dt>
  <dd><p>The text or partial text for the which the command will wait to appear. Default is blank (empty), which means to wait for the status bar to become blank. The text is case sensitive and the matching behavior is determined by <a href="SetTitleMatchMode.htm">SetTitleMatchMode</a>, similar to <em>WinTitle</em> below.</p>
    <p>To instead wait for the bar's text to <em>change</em>, either use <a href="StatusBarGetText.htm">StatusBarGetText</a> in a loop, or use the RegEx example at the bottom of this page.</p></dd>

  <dt>Timeout</dt>
  <dd><p>The number of seconds (can contain a decimal point or be an <a href="../Variables.htm#Expressions">expression</a>) to wait before timing out, in which case <a href="../misc/ErrorLevel.htm">ErrorLevel</a> will be set to 1. Default is blank, which means the command will wait indefinitely. Specifying 0 is the same as specifying 0.5.</p></dd>

  <dt>Part#</dt>
  <dd><p>Which part number of the bar to retrieve, which can be an <a href="../Variables.htm#Expressions">expression</a>. Default 1, which is usually the part that contains the text of interest.</p></dd>

  <dt>WinTitle</dt>
  <dd><p>A window title or other criteria identifying the target window. See <a href="../misc/WinTitle.htm">WinTitle</a>.</p></dd>

  <dt>WinText</dt>
  <dd><p>If present, this parameter must be a substring from a single text element of the target window (as revealed by the included Window Spy utility). Hidden text elements are detected if <a href="DetectHiddenText.htm">DetectHiddenText</a> is ON.</p></dd>

  <dt>Interval</dt>
  <dd><p>How often the status bar should be checked while the command is waiting (in milliseconds), which can be an <a href="../Variables.htm#Expressions">expression</a>. Default is 50. </p></dd>

  <dt>ExcludeTitle</dt>
  <dd><p>Windows whose titles include this value will not be considered.</p></dd>

  <dt>ExcludeText</dt>
  <dd><p>Windows whose text include this value will not be considered.</p></dd>

</dl>

<h2>Error Handling</h2>
<p><span class="ver">[v1.1.04+]</span>: This command is able to throw an exception if the status bar couldn't be accessed. For more information, see <a href="Catch.htm#RuntimeErrors">Runtime Errors</a>.</p>
<p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 1 if the command times out before a match could be found in the status bar. It is set to 2 if the status bar could not be accessed. It is set to 0 if a match is found.</p>
<h2>Remarks</h2>
<p>StatusBarWait attempts to read the first <em>standard</em> status bar on a window (class msctls_statusbar32). Some programs use their own status bars or special versions of the MS common control. Such bars are not supported.</p>
<p>Rather than using <a href="StatusBarGetText.htm">StatusBarGetText</a> in a loop, it is usually more efficient to use StatusBarWait because it contains optimizations that avoid the overhead that repeated calls to <a href="StatusBarGetText.htm">StatusBarGetText</a> would incur.</p>
<p>StatusBarWait determines its target window before it begins waiting for a match. If that target window is closed, the command will stop waiting even if there is another window matching the specified <em>WinTitle</em> and <em>WinText</em>.</p>
<p>While the command is in a waiting state, new <a href="../misc/Threads.htm">threads</a> can be launched via <a href="../Hotkeys.htm">hotkey</a>, <a href="Menu.htm">custom menu item</a>, or <a href="SetTimer.htm">timer</a>.</p>
<p>Window titles and text are case sensitive. Hidden windows are not detected unless <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> has been turned on.</p>

<h2>Related</h2>
<p><a href="StatusBarGetText.htm">StatusBarGetText</a>, <a href="WinGetTitle.htm">WinGetTitle</a>, <a href="WinGetText.htm">WinGetText</a>, <a href="ControlGetText.htm">ControlGetText</a></p>
<h2>Examples</h2>
<div class="ex" id="ExSearch">
<p><a href="#ExSearch">#1</a>: The following example enters a new search pattern into an existing Explorer/Search window.</p>
<pre>if WinExist("Search Results") <em>; Sets the Last Found window to simplify the below.</em>
{
    WinActivate
    Send, {tab 2}!o*.txt{enter}  <em>; In the Search window, enter the pattern to search for.</em>
    Sleep, 400  <em>; Give the status bar time to change to &quot;Searching&quot;.</em>
    StatusBarWait, found, 30
    if ErrorLevel
        MsgBox, The command timed out or there was a problem.
    else
        MsgBox, The search successfully completed.
}</pre>
</div>

<div class="ex" id="ExChange">
<p><a href="#ExChange">#2</a>: The following example waits for the status bar of the active window to <strong>change</strong>. This example requires <span class="ver">[v1.0.46.06+]</span>.</p>
<pre>SetTitleMatchMode RegEx  <em>; Accept <a href="SetTitleMatchMode.htm#RegEx">regular expressions</a> for use below.</em>
if WinExist("A")  <em>; Set the last-found window to be the active window (for use below).</em>
{
    StatusBarGetText, <span class="red">OrigText</span>
    StatusBarWait, ^(?!^\Q<span class="red">%OrigText%</span>\E$)  <em>; This regular expression waits for any change to the text.</em>
}</pre>
</div>

</body>
</html>
